home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / os20 / cdity / smaus117.lha / SMaus.doc < prev    next >
Text File  |  1993-04-06  |  22KB  |  526 lines
  1.  
  2.  
  3.  
  4.                                Documentation
  5.  
  6.                                     for
  7.  
  8.                                    SMaus
  9.  
  10.  
  11.  
  12.                    Copyright © 1991, 1992 Stefan Sticht
  13.  
  14.                             All rights reserved
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                                  Shareware
  22.  
  23.      SMaus is shareware. SMaus is not freeware. If you use  SMaus  you
  24.      must register your copy.
  25.  
  26.  
  27.                                Registration
  28.  
  29.      To  register  your  copy  of  SMaus  print  out  the  file  named
  30.      "Registration", fill it out and send  it  to  me  along  with  an
  31.      euro-cheque, money order or cash.  The  registration  fee  is  US
  32.      $5.-/DM 5.-.
  33.  
  34.  
  35.                                 No warranty
  36.  
  37.      THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED  BY
  38.      APPLICABLE LAW. EXCEPT  WHEN  OTHERWISE  STATED  IN  WRITING  THE
  39.      COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE  THE  PROGRAM  "AS
  40.      IS" WITHOUT WARRANTY OF ANY KIND, EITHER  EXPRESSED  OR  IMPLIED,
  41.      INCLUDING,  BUT  NOT  LIMITED  TO,  THE  IMPLIED  WARRANTIES   OF
  42.      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE  ENTIRE
  43.      RISK AS TO THE QUALITY AND PERFORMANCE OF  THE  PROGRAM  IS  WITH
  44.      YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE  COST  OF
  45.      ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  46.      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW  OR  AGREED  TO  IN
  47.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY  OTHER  PARTY  WHO  MAY
  48.      REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  49.      DAMAGES,  INCLUDING   ANY   GENERAL,   SPECIAL,   INCIDENTAL   OR
  50.      CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO  USE
  51.      THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF  DATA  OR  DATA
  52.      BEING RENDERED INACCURATE OR LOSSES SUSTAINED  BY  YOU  OR  THIRD
  53.      PARTIES OR A FAILURE OF THE PROGRAM TO  OPERATE  WITH  ANY  OTHER
  54.      PROGRAM), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED  OF
  55.      THE POSSIBILITY OF SUCH DAMAGES.
  56.  
  57.  
  58.                                Distribution
  59.  
  60.      You may copy and distribute  verbatim  copies  of  the  program's
  61.      executable code and documentation  as  you  receive  it,  in  any
  62.      medium, provided that you conspicuously and appropriately publish
  63.      only the original, unmodified program, with all copyright notices
  64.      and  disclaimers  of  warranty  intact  and  including  all   the
  65.      accompanying documentation, example files and anything else  that
  66.      came with the original. You may only charge a small fee  for  the
  67.      costs  of  media,  handling  and  postage.  SMaus  may   not   be
  68.      distributed along with or as part of commercial products  without
  69.      a license from the author.
  70.  
  71.      SMaus_nowin is a special version of SMaus  without  a  graphical
  72.      user interface. Everything said for SMaus applies to SMaus_nowin,
  73.      too.
  74.  
  75.  
  76.                                Introduction
  77.  
  78.      SMaus has been written to replace the commodity AutoPoint,  which
  79.      is part of AmigaOS 2.0 and above. SMaus is highly configurable.
  80.  
  81.      The primary purpose  is  to  activate  windows  under  the  mouse
  82.      pointer. There  are  different  actions  which  will  activate  a
  83.      window:
  84.  
  85.      Mouse movement: while or after moving the mouse the window  under
  86.      the pointer gets activated. You can select a  speed  below  which
  87.      windows get activated. If you move the mouse fast, no window gets
  88.      activated. If you move the mouse slowly, the  windows  under  the
  89.      mouse  get  activated.  In  the  one  extrem,  windows  only  get
  90.      activated after  you  stopped  the  mouse  movement.  This  helps
  91.      minizing the "jumping" of the pointer on 68000 based Amigas  when
  92.      a window gets activated, because AmigaOS has to redraw the border
  93.      of the window which got activated and has no time left for moving
  94.      the pointer. After the  border  has  been  redrawn,  the  pointer
  95.      jumps. On faster Amigas, e.g. the A3000, the  "jumping"  is  less
  96.      noticable, at least when you  move  the  mouse  slowly.  On  this
  97.      machines you can allow SMaus to activate windows at once, as long
  98.      as you move the mouse slowly.
  99.  
  100.      Time: Unfortunately SMaus and Autopoint can't be informed by  the
  101.      OS, if a new window or screen has been opened or the front screen
  102.      has been changed. Therefore SMaus and Autopoint  always  have  to
  103.      look which window is under the  mouse  pointer  after  a  certain
  104.      time. This technic is known as "polling" and  must  be avoided on
  105.      multitasking operating systems like AmigaOS. But  as  the  window
  106.      under the mouse pointer should be active, SMaus  for  example has
  107.      to test if another window opened active and the window under  the
  108.      pointer has to be reactivated, etc. With SMaus you can select the
  109.      time, after which SMaus tests this, or  disable  this  option  at
  110.      all. You may increase the timeout to minimize CPU usage. With the
  111.      additional option "Keypress" (described below) you may  select  a
  112.      great timeout without disadvantages.
  113.  
  114.      Keypress: If you like it, SMaus activates the  window  under  the
  115.      pointer at any key pressed.
  116.  
  117.      Mousemovement by keyboard: SMaus recognizes  mousemovements  done
  118.      by keyboard using  an  Amiga  key  and  the  cursor  keys.  SMaus
  119.      activates the window under the pointer after movement.
  120.  
  121.      Often it would be better not to activate  the  window  under  the
  122.      pointer. The  following  options disable  the  window  activation
  123.      temporarily:
  124.  
  125.      Window title: you can specify titles of windows, which are  never
  126.      to  be  deactivated.  You  can  use  normal   AmigaOS   wildcards
  127.      therefore. Thus you can tell SMaus not to deactivate e.g. windows
  128.      called "System request" or "Arq", because you'd  like  to  answer
  129.      this requesters with the keyboard immediately.
  130.  
  131.      Screen title: like window titles, you may specify screen  titles.
  132.      If the screen title of the frontmost screen matches,  SMaus  does
  133.      nothing on this screen.
  134.  
  135.      System  requesters:  they  don't  get  deactivated.  This  option
  136.      doesn't work with some requester replacements like "Arq".
  137.  
  138.      Already active windows don't get activated  again.  SMaus  has  a
  139.      graphical user interface for easy configuration. You can  save  a
  140.      configuration and load it. SMaus has been  programmed  respecting
  141.      the rules of AmigaOS. No OS functions get patched. SMaus has been
  142.      programmed on an A3000 with SAS/C and has been  tested  with  the
  143.      debugging tools Enforcer and Mungwall.
  144.  
  145.  
  146.                             System requirements
  147.  
  148.      SMaus requires at least AmigaOS 2.04, Kickstart  version  37.175.
  149.      If you have Workbench 2.1, version 38.xx or better, you can use a
  150.      localized user interface. This means SMaus uses messages in  e.g.
  151.      german language. SMaus will not work with AmigaOS 1.2 or 1.3.
  152.  
  153.  
  154.                               Starting SMaus
  155.  
  156.      Before you test  SMaus,  please  make  sure  you're  not  running
  157.      autopoint at  the  same  time.  Remove  autopoint  by  using  the
  158.      Commodities Exchange utility provided by AmigaOS.
  159.  
  160.      You may start SMaus either from Shell or by  double  clicking  on
  161.      its icon. If you haven't changed any tool type in  SMaus's  icon,
  162.      double clicking on it starts SMaus and tells the program to  open
  163.      its window immediately. As SMaus can't run  twice  simultanously,
  164.      because there's no sense in doing so. Starting SMaus  twice  will
  165.      tell the first running copy of SMaus to open its window.  If  you
  166.      want to start SMaus from the shell and be able to close the shell
  167.      afterwards, use
  168.  
  169.                            Run >NIL: <path>SMaus
  170.  
  171.      to start it.
  172.  
  173.      Now it's time to explain the various options:
  174.  
  175.  
  176.                                   Options
  177.  
  178.      Activation Threshold:
  179.  
  180.      With the top most slider in SMaus's window  you  can  change  the
  181.      threshold for the speed of mouse movement,  above  which  windows
  182.      don't get activated at once. The speed of movement is measured in
  183.      pixel/event. Just test this: select a threshold of  0.  Now  move
  184.      the pointer across window borders. Nothing will  happen.  But  if
  185.      you  stop  the  movement,  the  window  under  the  pointer  gets
  186.      activated. Threshold 0 means: activate after movement. You  might
  187.      prefer this on 68000 based machines. Now select a threshold of  2
  188.      and move the mouse very slowly across window borders. The windows
  189.      will get activated immediately. Now move the pointer fast over a
  190.      window without stopping in his boundaries. The window didn't  get
  191.      activated. Why? Just increase the threshold and do it again.  The
  192.      window got activated, if the threshold was big  enough,  but  you
  193.      may have noticed this ugly "jumping" of the mouse pointer. On  my
  194.      A3000 I prefer a threshold of 1.
  195.  
  196.      Reactivate windows after:
  197.  
  198.      The second slider determines the time, after which SMaus tests if
  199.      the window under the mouse pointer is  still  active.  If  it  is
  200.      inactive, it will be reactivated. This  timeout  is  measured  in
  201.      1/10  seconds.  0/10  disables  this  feature.  Default  is  5/10
  202.      seconds, what means half a second. Increasing  this  value  saves
  203.      CPU time. If you use the option "Keypress", too, you may increase
  204.      this value without any disadvantages.
  205.  
  206.      Don't deactivate this windows:
  207.  
  208.      In this string gadget you can specify titles  of  windows,  which
  209.      are not to be deactivated. You may use normal AmigaOS  wildcards.
  210.      Example: Arq#? doesn't disable windows with a title  that  starts
  211.      with  Arq.  For  further  information  read  the  chapter   about
  212.      wildcards  in  your  AmigaDOS  manual.  Please  note,  that   the
  213.      comparison is case dependant. Some more examples:
  214.  
  215.      (Arq#?|#?estion#?)  -  all  titles  beginning   with   "Arq"   or
  216.      containing "estion", e.q. question.
  217.  
  218.      (#?[Rr]equest|Arq#?|#?[Mm]essage|Choose #?) -  all  titles,  that
  219.      end with "Request" or "request", or start with "Arq" or "Choose".
  220.  
  221.      If the pattern is  not  syntactically  correct,  e.g.  a  bracket
  222.      misses, SMaus will tell you this.
  223.  
  224.      Do nothing on these screens:
  225.  
  226.      In  this  string  gadget  you  specify  titles  of  screens,  with
  227.      wildcards, as above.  If the title of the frontmost screen matches
  228.      the contents of this stringgadget, SMaus does absolutely nothing.
  229.  
  230.      Hotkey to open this window:
  231.  
  232.      In this string gadget you put a description of the hotkey,  which
  233.      shall open SMaus's window. Examples:
  234.  
  235.      lcommand f1 - open window on left Amiga + F1
  236.      ctrl help   - open window on ctrl + help key
  237.  
  238.      SMaus uses commodities.library's input description strings:
  239.  
  240.                          Input description strings
  241.  
  242.      With input description strings you can specify almost  any  input
  243.      action, for example the action lshift f1, that is  pressing  the
  244.      left shift and the f1 key together.
  245.  
  246.      Input description strings have the following template:
  247.  
  248.          [class] (([-]qual)|syn)* [[-]upstroke] [highmap|ANSIcode]
  249.  
  250.      (* means: zero or more occurances of the expression in brackets)
  251.  
  252.      class   is one of the following strings:
  253.              rawkey, rawmouse, event, pointerpos, timer, newprefs,
  254.              diskremoved, diskinserted.
  255.              If not specified, the class is supposed to be "rawkey".
  256.  
  257.      qual    is one of the strings:
  258.              lshift, rshift, capslock, control, lalt, ralt, lcommand,
  259.              rcommand, numericpad, repeat, midbutton, rbutton,
  260.              leftbutton, relativemouse
  261.              A preceding '-' means that the value of the corresponding
  262.              qualifier is to be considered irrelevant.
  263.  
  264.      syn     (synonym) is one of the strings: shift, caps, alt
  265.              shift means "left or right shift"
  266.              caps means "shift or capslock"
  267.              alt means "either alt key"
  268.  
  269.      upstroke (literally "upstroke")
  270.              if this token is absent, only downstrokes are considered
  271.              for rawmouse (mousebuttons) and rawkey events.  If only
  272.              this is present, only upstrokes count.  If it is preceded
  273.              by '-'  both, up and down strokes, are included.
  274.  
  275.      highmap one of the strings:
  276.              comma, space, backspace, tab, enter, return, esc, del, up,
  277.              down, right, left, help, f1, f2, f3, f4, f5, f6, f7, f8,
  278.              f9, f10, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, (, ), /, *, -, +
  279.  
  280.      ansicode a single character token is interpreted as a character
  281.              code, which is looked up in the system default keymap.
  282.  
  283.      The names of the keywords above may vary  in  other  versions  of
  284.      AmigaOS or new descriptors may be added.  SMaus  will  unterstand
  285.      them. Please consult your AmigaOS documentation.
  286.  
  287.      Activate by mouse:
  288.  
  289.      With this cycle  gadget  you  select  if  mouse  movements  shall
  290.      activate the window under the pointer at  all  and  wether  mouse
  291.      movements shall activate normally or  always.  "Normally"  means:
  292.      activate,  if  not  the  options  "WindowNot"  or  "StringGadNot"
  293.      prohibit the activation. E.g. if a string gadget  is  active,  no
  294.      window will be activated. "Always" means activate really always.
  295.  
  296.      Activate by key:
  297.  
  298.      When this option is enabled, SMaus activates the window under the
  299.      mouse pointer if you press any key of the keyboard.
  300.  
  301.      Don't deactivate windows with active string gadget:
  302.  
  303.      If you enable this, SMaus won't deactivate  windows  with  active
  304.      string gadgets. Please notice, that this will not work  correctly
  305.      if you specify a too small timeout for reactivation  of  windows,
  306.      because a program  might  open  a  window  and  before  it  could
  307.      activate the string gadget, SMaus may  already  have  deactivated
  308.      its window.
  309.  
  310.  
  311.                                Other gadgets
  312.  
  313.      Hide:
  314.  
  315.      This button or the close gadget or  the  ESC  key  close  SMaus's
  316.      window without quitting.
  317.  
  318.      About:
  319.  
  320.      This shows you some information about the program.
  321.  
  322.      Quit:
  323.  
  324.      This button removes SMaus completely.
  325.  
  326.  
  327.                                    Menu
  328.  
  329.      Configuration open/save:
  330.  
  331.      With this two menu items you can save all your prefered  settings
  332.      in a  selectable  config  file  or  load  a   previously   saved
  333.      configuration.
  334.  
  335.  
  336.                                Installation
  337.  
  338.      If you want to start SMaus any time you boot   your  Amiga,  just
  339.      drag SMaus's icon to your WBStartup drawer. If you'd  like  SMaus
  340.      to use other languages, e.g.  german,  please  read  the  chapter
  341.      "languages".
  342.      If you want to start SMaus in your User-Startup, add the line
  343.  
  344.                       Run >NIL: <path>SMaus <otions>
  345.  
  346.      to it,  after  replacing  <path>  with  the  path  to  the  SMaus
  347.      executable and <options> with your prefered options. Example:
  348.  
  349.                Run >NIL: SYS:Tools/SMaus from s:SMaus.config
  350.  
  351.  
  352.                                 Tool Types
  353.  
  354.     You may add the following tooltypes  to  its  icon  to  configure
  355.     SMaus:
  356.  
  357.      From=<filename>         The name of a configfile to load.
  358.                              The configfile will be read before
  359.                              other tool types are parsed. So
  360.                              tool types will overrule the same
  361.                              options of the configfile.
  362.  
  363.      CX_Priority=<num>       The priority of SMaus in the list of
  364.                              commodities.
  365.  
  366.      CX_Popkey=<string>      The input description string for the
  367.                              hotkey.
  368.  
  369.      CX_Popup                If Smaus finds this tool type, it will
  370.                              immediately open its window.
  371.  
  372.      Timeout=<num>           The prefered timeout for window
  373.                              reactivation.
  374.  
  375.      Threshold=<num>         Threshold in pixel/event below which
  376.                              windows get activated immediately by
  377.                              mouse movement.
  378.  
  379.      Priority=<num>          The priority of the SMaus process.
  380.                              If you use the option "keypress", the
  381.                              priority gets automatically raised to
  382.                              21.
  383.  
  384.      WindowNot=<string>      The pattern describing windows which
  385.                              are not to be deactivated.
  386.  
  387.      ScreenNot=<String>      The pattern describing the screens on
  388.                              which SMaus mustn't do anything.
  389.  
  390.      Keypress                Turn on activation by keypress.
  391.  
  392.      MouseNever              Turn off activation by mouse.
  393.  
  394.      MouseAlways             Mouse movements activate always.
  395.  
  396.      NoStringGad             Don't deactivate windows with active
  397.                              string gadgetgs
  398.  
  399.      Here's the template if you want to start SMaus from Shell:
  400.  
  401.      CX_Priority/K/N,CX_Popkey/K,CX_Popup/S,Timeout/K/N,Threshold/K/N,
  402.      Priority/K/N,ScreenNot/K,WindowNot/K,Keypress/S,MouseNever/S,
  403.      MouseAlways/S,NoStringGad/S,From/K
  404.  
  405.      As you see these options are the same as the tool types. Please
  406.      notice that you have to put double quotes around options,
  407.      which contain a blank. Example:
  408.  
  409.                             cx_popkey "ctrl f1"
  410.  
  411.  
  412.                                 Config file
  413.  
  414.      SMaus's config file is an ASCII file, that means, you may  create
  415.      and change this file with your prefered editor. Every line in the
  416.      configfile has to look like the options part if you  start  SMaus
  417.      from a Shell. Lines starting with ";" are treated as comments.
  418.      Example of a configfile:
  419.  
  420.           ---- beginning of file ----
  421.           ; Comment
  422.           KeyPress NoStringGad
  423.           MouseAlways
  424.           Threshold 1
  425.           Timeout 10
  426.           ScreenNot "Post#?"
  427.           WindowNot "(Arq#?|#?equest #?|#?essage#?|System#?)"
  428.           CX_Popkey "lcommand control f2"
  429.           ---- end of file ----
  430.  
  431.      Please  notice  again  the  double  quotes  around  options  line
  432.      WindowNot. Please notice  also,  that  saving  the  configuration
  433.      within SMaus creates a completly new config file. Comments in the
  434.      old config file will be lost.
  435.  
  436.  
  437.                                 SMaus_nowin
  438.  
  439.      SMaus_nowin is a special version of  SMaus  without  a  graphical
  440.      user interface and without a window. If you're short  on  memory,
  441.      this version saves you some of it.
  442.  
  443.  
  444.                                  Languages
  445.  
  446.      If you use Workbench V2.1 or higher, you have  a  library  called
  447.      "locale.library". This library  allows  programs  easy  usage  of
  448.      message catalogs in different  languages.  SMaus  plus  a  german
  449.      message catalog makes an SMaus with a german user interface, with
  450.      german error messages etc. If you've got a  message  catalog  for
  451.      SMaus in your native language, you  can  have  SMaus  using  your
  452.      language. But these message catalogs must be created  exclusively
  453.      for every  program.  The  message  catalog  for  SMaus  is  named
  454.      SMaus.catalog.  Unfortunately  I  only  speak  German  and   some
  455.      English, so I can only provide you with a German message  catalog
  456.      (the English message catalog is built in). But you may  create  a
  457.      message catalog for SMaus in your native language if you  have  a
  458.      software developing tool called "CatComp" by Commodore:
  459.  
  460.      First create a directory Catalogs/<language> in SMaus's  catalogs
  461.      directory. With
  462.  
  463.            CatComp SMaus.cd CTFILE Catalogs/<language>/SMaus.ct
  464.  
  465.      you make  an empty  translation file. Fill up the empty lines  in
  466.      this file with the translation of the english messages below  the
  467.      empty line. After this insert  "SMaus.catalog"  and  the  version
  468.      number 1.0 in the first line. In  the  third  line  you  have  to
  469.      insert the name of the language, as you  can  select  it  in  the
  470.      prefs editor "Locale", e.g. français. With
  471.  
  472.            CatComp SMaus.cd Catalogs/<language>/SMaus.ct CATALOG
  473.                    catalogs/<language>/SMaus.catalog"
  474.  
  475.      you create the message catalog for <language>.
  476.  
  477.      If you have a message catalog for SMaus in a language you want,
  478.      you have to do this to make SMaus use this catalog.
  479.  
  480.      First, you have to choose the language as the prefered language
  481.      in the preferences editor Locale.
  482.  
  483.      Second,  locale.library  must  be   able   to   find   the   file
  484.      SMaus.catalog.  locale.library  tries  to  open  the  catalog  as
  485.      Catalogs/<language>/SMaus.catalog in  the  directory,  where  the
  486.      SMaus executable resides. If it can't find it there, it tries  to
  487.      open Locale:catalogs/<language>/SMaus.catalog.
  488.  
  489.      Now you may copy SMaus.catalog to  Locale:catalogs/<language>  or
  490.      create a subdirectory catalogs/<language> in the directory, where
  491.      the SMaus executable resides and copy SMaus.catalog there.
  492.  
  493.      PLEASE send me  the translation files if you translate SMaus into
  494.      your native language. Thank you!
  495.  
  496.  
  497.                                   History
  498.  
  499.      V1.15   first international version of SMaus
  500.      V1.16   not released
  501.      V1.17   changed small bug in the code which reads the config file
  502.              which could lead to loosing some bytes (140 or so);
  503.              checkmark gadgets are now scaled;
  504.              recompiled with SAS/C 6.2
  505.  
  506.  
  507.                                   Support
  508.      
  509.      If you have any suggestions,  bug  reports  etc.,  feel  free  to
  510.      contact the author of SMaus at the below address.
  511.  
  512.  
  513.          Stefan Sticht
  514.          Bibereckerweg 40a
  515.          D-8390 Passau 18
  516.          Germany
  517.  
  518.          EMail:
  519.          Internet: sticht@edith.deg.sub.org
  520.          Fido: Stefan Sticht (2:246/200.4)
  521.  
  522.  
  523.      T h a n k  y o u  f o r  r e g i s t e r i n g!
  524.  
  525.      Greetings, Stefan Sticht
  526.